---
order: 4
title: Text Renderer
type: Graphics
group: 2D
label: Graphics/2D
---

The [TextRenderer](/apis/core/#TextRenderer) component is used to display text in 3D/2D scenes, supporting features such as dynamic text, custom fonts, multi-line display, alignment, and more.

## Editor Usage

### Adding a Text Component
1. Select the target entity in the scene.
2. Add a **TextRenderer** component via the entity property panel.
3. Configure component parameters to define the text style.

<Image 
  src="https://mdn.alipayobjects.com/huamei_w6ifet/afts/img/A*3d5AQYTtcNkAAAAAAAAAAAAADjCHAQ/original" 
  alt="Illustration of adding a TextRenderer component" 
/>

### Parameter Description
Select an entity with a TextRenderer component and configure the following properties in the right-side **Inspector** panel:

<Image 
  src="https://mdn.alipayobjects.com/huamei_w6ifet/afts/img/A*9XKjSYHZQWsAAAAAAAAAAAAADjCHAQ/original" 
  alt="Illustration of TextRenderer component property panel" 
/>

| Property                | Description                                                                 |
|-------------------------|-----------------------------------------------------------------------------|
| **Text**                | The text content to display (supports multi-line input)                    |
| **Color**               | Text color (RGBA format)                                                   |
| **FontSize**            | Font size (unit: pixels)                                                   |
| **Font**                | Custom font resource (defaults to system font)                             |
| **Width**               | Design width of the text (affects line wrapping and layout, unit: scene units) |
| **Height**              | Design height of the text (affects truncation and layout, unit: scene units) |
| **LineSpacing**         | Line spacing (unit: pixels)                                                |
| **FontStyle**           | Font style: `None` (default) / `Bold` (bold) / `Italic` (italic)           |
| **HorizontalAlignment** | Horizontal alignment: `Left` (left) / `Center` (center) / `Right` (right)  |
| **VerticalAlignment**   | Vertical alignment: `Top` (top) / `Center` (center) / `Bottom` (bottom)    |
| **EnableWrapping**      | Whether to enable automatic line wrapping (requires valid `Width`)         |
| **OverflowMode**        | Overflow handling: `Overflow` (show overflowed content) / `Truncate` (truncate overflow) |
| **Mask Interaction**    | Mask interaction mode (used with SpriteMask)                               |
| **Mask Layer**          | Mask layer (defaults to `Everything` to match all layers)                  |
| **Priority**            | Render priority (lower values render earlier)                              |

<Callout type="info">`Width` and `Height` are used to define the layout range of the text (e.g., line wrapping and alignment), not the actual rendering size. To obtain the real bounding box size of the text in 3D space, read the `TextRenderer.bounds` property.</Callout>

### Basic Operation Examples

#### Setting Text Content
1. Enter the target text in the **Text** property field.
2. Directly input multi-line text with line breaks.

<Image 
  src="https://mdn.alipayobjects.com/huamei_w6ifet/afts/img/A*J6nKTJOOm4kAAAAAAAAAAAAADjCHAQ/original" 
  alt="Example of setting text content" 
/>

#### Using Custom Fonts
1. Prepare font files (supports `.ttf`, `.otf`, `.woff` formats).
2. Drag and drop the font files into the editor's resource panel.
3. Select the uploaded font in the **Font** property.

<Image 
  src="https://mdn.alipayobjects.com/huamei_w6ifet/afts/img/A*CgA5S5vneeMAAAAAAAAAAAAADjCHAQ/original" 
  alt="Illustration of custom font settings" 
/>

## Script Development Guide

### Basic Usage
```typescript
import { TextRenderer, Font, Color } from "@galacean/engine";

// Create a text entity and add a component
const textEntity = rootEntity.createChild("text");
const textRenderer = textEntity.addComponent(TextRenderer);

// Set basic properties
textRenderer.text = "Galacean Text Rendering";  // Text content
textRenderer.fontSize = 24;                   // Font size (pixels)
textRenderer.color = new Color(1, 0, 0, 1);    // Red text
```

### Advanced Features

#### 1. Custom Font Loading
```typescript
// Method 1: Use system font
textRenderer.font = Font.createFromOS(engine, "Arial");

// Method 2: Load external font file
engine.resourceManager.load({ url: "fonts/Avelia.otf" }).then((font) => {
  textRenderer.font = font;
});
```

#### 2. Layout and Wrapping
```typescript
// Set bounding box size (unit: scene units)
textRenderer.width = 5;   // Controls auto-wrap width
textRenderer.height = 3;  // Affects truncation height

// Enable auto-wrap
textRenderer.enableWrapping = true;

// Set line spacing
textRenderer.lineSpacing = 0.5;
```

#### 3. Overflow and Truncation
```typescript
// Set overflow mode
textRenderer.overflowMode = OverflowMode.Truncate; // or OverflowMode.Overflow

// Alignment (requires width/height)
textRenderer.horizontalAlignment = TextHorizontalAlignment.Center;
textRenderer.verticalAlignment = TextVerticalAlignment.Top;
```

#### 4. Font Style Combinations
```typescript
// Apply bold and italic simultaneously
textRenderer.fontStyle = FontStyle.Bold | FontStyle.Italic;
```

## Notes
1. **Zero Width/Height Trap**: If line wrapping is enabled (`enableWrapping=true`) but no valid width/height is set, the text will not render.
2. **Font Compatibility**: Some complex fonts (e.g., those containing variant characters) may render abnormally. Testing is recommended.
3. **Performance Optimization**: Frequent text updates may impact performance. Batch rendering is advised for static text.

## API Reference
| Class/Enum                  | Key Properties/Values                              | Description                          |
|----------------------------|----------------------------------------------------|--------------------------------------|
| `TextRenderer`             | `text`, `font`, `fontSize`                         | Main class for text rendering        |
| `TextHorizontalAlignment`  | `Left`, `Center`, `Right`                          | Horizontal alignment modes           |
| `TextVerticalAlignment`    | `Top`, `Center`, `Bottom`                          | Vertical alignment modes             |
| `FontStyle`                | `None`, `Bold`, `Italic`                           | Font style combinations              |